/*
 * Copyright 2008. Mount Sinai Hospital, Toronto, Canada.
 * 
 * Licensed under the Apache License, Version 2.0. You
 * can find a copy of the license at:
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * IN NO EVENT SHALL MOUNT SINAI HOSPITAL BE LIABLE TO ANY PARTY FOR DIRECT, 
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST 
 * PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, 
 * EVEN IF MOUNT SINAI HOSPITAL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 
 * DAMAGE.
 * 
 * MOUNT SINAI HOSPITAL SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF 
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND 
 * ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS PROVIDED "AS IS". 
 * MOUNT SINAI HOSPITAL HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, 
 * UPDATES, ENHANCEMENTS, OR MODIFICATIONS. 
 */

package com.sinai.mshab.visibility;

/**
 * The <code>NestedVisibilityController</code> provides a way to nest
 * {@link VisibilityRule} in such a way that certain {@link VisibilityRule} have
 * precedence over others. This allows for hierarchical layout of visibility
 * rules.
 * 
 * @author Arthur Kalmenson
 */
public interface NestedVisibilityController extends VisibilityController {

	/**
	 * Sets the root {@link VisibilityRule}. If <code>root</code> is null, an
	 * {@link IllegalArgumentException} is thrown.
	 * 
	 * @param root
	 *            the root rule.
	 */
	public void setRootRule(VisibilityRule<?, ?, ?> root);

	/**
	 * Adds a child {@link VisibilityRule}, this rule will be executed before
	 * the parent rule to insure the parent's rule takes precedence. The parent
	 * must already be in the <code>NestedVisibilityController</code> otherwise
	 * an {@link IllegalStateException} is thrown. Both parent and child must be
	 * instantiated or an {@link IllegalArgumentException} is thrown.
	 * 
	 * @param parent
	 *            the parent rule that will override the child rule.
	 * @param child
	 *            the child rule that will run before the parent.
	 */
	public void addParentChildRule(VisibilityRule<?, ?, ?> parent,
			VisibilityRule<?, ?, ?> child);

	/**
	 * Executes all the {@link VisibilityRule}s that this
	 * <code>NestedVisibilityController</code> has. The rules are executed in
	 * such a way that the parent rules take precedence over the child rules.
	 */
	public void executeAll();
}
